@brett_lamy/docstream-editor 0.6.0 → 0.8.0

package/README.md

@@ -75,6 +75,11 @@ export interface GitbookEditorProps {
   onChange: (markdown: string) => void
   onKeyDown?: (event: KeyboardEvent) => boolean
   onPaste?: (event: ClipboardEvent) => boolean
+  imagePaste?: "inline" | "chip"
+  attachments?: EditorAttachment[]
+  onAttachmentAdd?: (attachment: EditorAttachment & { file: File }) => void
+  onAttachmentRemove?: (ids: string[]) => void
+  onAttachmentOpen?: (attachment: EditorAttachment) => void
 }
 ```
 
@@ -82,6 +87,8 @@ export interface GitbookEditorProps {
 - `onChange`: Called with serialized markdown whenever TipTap content changes.
 - `onKeyDown` / `onPaste`: Optional host hooks that run before the built-in editor behavior;
   return `true` when the application handled the event.
+- `imagePaste`, `attachments`, `onAttachmentAdd`, `onAttachmentRemove`, `onAttachmentOpen`:
+  how pasted/dropped images are handled — see [Pasted and dropped images](#pasted-and-dropped-images).
 
 The editor tracks the last markdown it emitted so normal controlled updates do not continuously reset the TipTap document. Passing a different external `markdown` value replaces the editor content.
 
@@ -109,6 +116,65 @@ The editor supports common ProseMirror/TipTap content plus GitBook-flavored bloc
 
 Some blocks are intentionally represented as structured nodes rather than fully bespoke editing controls. They are preserved through parse, edit, and serialize flows so the document can continue to round-trip as GitBook-style markdown.
 
+## Mentions, channels, and codebases
+
+Typing `@`, `#`, or `$` opens a picker and inserts a reference chip that serializes as
+`@id`, `#id`, or `$id` (`$org/repo` works too). Feed each trigger a static list or an
+async `(query) => options` function; options can carry a `label`, `description`, and
+`group` (rendered as section headers). `$` is only enabled when `codebases` is set, so
+dollar signs in ordinary prose never open a menu. Free-form entry is always offered.
+
+```tsx
+<GitbookEditor
+  markdown={md}
+  onChange={setMd}
+  references={{
+    mentions: [
+      ...people.map((p) => ({ id: p.handle, label: p.name, description: p.email, group: "People" })),
+      ...agents.map((a) => ({ id: a.handle, label: a.name, description: a.harness, group: "Agents" })),
+    ],
+    tags: async (query) => searchChannels(query), // [{ id: "general", description: "channel" }]
+    codebases: async (query) => searchRepos(query), // [{ id: "reading-room" }]
+  }}
+/>
+```
+
+## Pasted and dropped images
+
+`imagePaste` controls how pasted or dropped image files enter the document. It runs after
+your `onPaste` (return `true` there to take over). Clipboard data that also carries plain
+text, such as a Word or Excel selection, still pastes as text.
+
+- `"inline"` (default): an image block with the file as a data URL, the way it will render.
+- `"chip"`: a compact attachment chip at the caret. The host stores the file. The chip
+  serializes as `![image.png](attachment:att-xyz)`, shows a thumbnail and size, previews the
+  full image on hover, and opens it on click.
+
+```tsx
+const [markdown, setMarkdown] = useState("")
+const [attachments, setAttachments] = useState<EditorAttachment[]>([])
+
+<GitbookEditor
+  markdown={markdown}
+  onChange={setMarkdown}
+  imagePaste="chip"
+  attachments={attachments}
+  // once per image: { id, name, src (data URL), size, type, file }
+  onAttachmentAdd={({ file, ...attachment }) => setAttachments((all) => [...all, attachment])}
+  // chips deleted, cut or cleared by the user
+  onAttachmentRemove={(ids) => setAttachments((all) => all.filter((a) => !ids.includes(a.id)))}
+  // optional; omit it to use the built-in full-screen viewer
+  onAttachmentOpen={(attachment) => openLightbox(attachment)}
+/>
+```
+
+`EditorAttachment` is `{ id, name, src?, size?, type? }`. Chips find their image in
+`attachments` by id, so `src` can be a data URL or an uploaded URL. To remove a chip
+from outside the editor, call `editor.commands.removeAttachment(id)` (get the instance
+from `onEditorReady`). Markdown images with an `attachment:` URL always load as chips,
+whatever the mode. `serializeEditorMarkdown(ast)` is the serializer that writes them in
+this form.
+
 ## Edit a referenced source file
 
 `GitbookEditor` edits the Markdown composition, including a structured
@@ -159,6 +225,8 @@ Exports:
 - `astToTiptap`
 - `tiptapToAst`
 - `PMNode`
+- `EditorAttachment`
+- `serializeEditorMarkdown`
 - `SourceFileEditor`
 - `SourceFileEditorProps`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream-editor",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "TipTap editor for Docstream GitBook-style markdown documents.",
   "type": "module",
   "scripts": {
@@ -33,7 +33,7 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@brett_lamy/docstream": "0.5.7",
+    "@brett_lamy/docstream": "0.7.0",
     "gpu-lexer": "0.0.2",
     "lucide-react": "^1.17.0"
   },

package/src/editor/Editor.tsx

@@ -10,13 +10,23 @@ import {
   Strikethrough,
 } from "lucide-react"
 
-import { parseMarkdown, serializeMarkdown, type CitationDef } from "@brett_lamy/docstream/gitbook"
+import { parseMarkdown, type CitationDef } from "@brett_lamy/docstream/gitbook"
 import type { SourceFileSnapshot, SourceReferenceClient } from "@brett_lamy/docstream/source"
-import { astToTiptap, tiptapToAst, type PMNode } from "./convert"
-import { createGitbookExtensions } from "./extensions"
+import {
+  attachmentName,
+  collectAttachmentIds,
+  imageFilesFrom,
+  newAttachmentId,
+  readFileAsDataURL,
+  type EditorAttachment,
+} from "./attachments"
+import { astToTiptap, serializeEditorMarkdown, tiptapToAst, type PMNode } from "./convert"
+import { createGitbookExtensions, type ReferenceSources } from "./extensions"
 import { EditorRuntimeProvider } from "./runtime"
 import type { SlashItem } from "./slash-menu"
 
+export type { EditorAttachment } from "./attachments"
+
 export interface GitbookEditorProps {
   /** Markdown source. When provided, the editor stays in sync with it (controlled). */
   markdown?: string
@@ -26,8 +36,11 @@ export interface GitbookEditorProps {
   toolbar?: boolean
   /** Built-in "/" slash menu: true (default), false, or a custom item list. */
   slashMenu?: boolean | { items?: SlashItem[] }
-  /** The "@" / "#" reference chip pickers: true (default), false, or known id lists. */
-  references?: boolean | { mentions?: string[]; tags?: string[] }
+  /**
+   * Reference chip pickers: true (default "@"/"#"), false, or per-trigger sources —
+   * static lists or async `(query) => options`. A `codebases` source enables "$".
+   */
+  references?: boolean | ReferenceSources
   /** Whether the document is editable (default true). */
   editable?: boolean
   /** Placeholder shown in an empty document. */
@@ -47,6 +60,20 @@ export interface GitbookEditorProps {
   onKeyDown?: (event: KeyboardEvent) => boolean
   /** Handle clipboard content before the editor's built-in paste behavior. Return true when handled. */
   onPaste?: (event: ClipboardEvent) => boolean
+  /**
+   * How pasted or dropped image files enter the document.
+   * "inline" (default) — an image block with the file as a data URL, as it will render.
+   * "chip" — a compact attachment chip at the caret; the host owns the file via `attachments`.
+   */
+  imagePaste?: "inline" | "chip"
+  /** Chip mode: the host's attachment store. Chips look up their thumbnail, full image and size here by id. */
+  attachments?: EditorAttachment[]
+  /** Chip mode: fired once per pasted/dropped image with a fresh id and the file read as a data URL. Add it to `attachments`. */
+  onAttachmentAdd?: (attachment: EditorAttachment & { file: File }) => void
+  /** Chip mode: fired when chips disappear from the document (deleted, cut, cleared) with their ids. */
+  onAttachmentRemove?: (ids: string[]) => void
+  /** Chip mode: clicking (or Enter/Space on a focused) chip. Omit to open the built-in image viewer. */
+  onAttachmentOpen?: (attachment: EditorAttachment) => void
   /** Receive the underlying TipTap editor instance (and null on teardown). */
   onEditorReady?: (editor: TiptapEditor | null) => void
   /** Client used to edit and preview `{% source-ref %}` files. */
@@ -135,6 +162,11 @@ export function GitbookEditor({
   extensions,
   onKeyDown,
   onPaste,
+  imagePaste = "inline",
+  attachments,
+  onAttachmentAdd,
+  onAttachmentRemove,
+  onAttachmentOpen,
   onEditorReady,
   sourceClient,
   sourcePreview = true,
@@ -149,6 +181,56 @@ export function GitbookEditor({
   // ones from the last applied markdown and reattach them on serialize.
   const citationsRef = useRef<CitationDef[] | undefined>(undefined)
   const controlled = markdown !== undefined
+  // Ids of the attachment chips in the document, to report removals.
+  const attachmentIds = useRef<Set<string>>(new Set())
+  // Latest callbacks for handlers the editor captured at creation.
+  const latest = useRef({ onPaste, imagePaste, onAttachmentAdd, onAttachmentRemove })
+  latest.current = { onPaste, imagePaste, onAttachmentAdd, onAttachmentRemove }
+  const editorRef = useRef<TiptapEditor | null>(null)
+
+  // Pasted/dropped image files: image blocks ("inline") or attachment chips ("chip").
+  const insertImageFiles = (files: File[], at?: number) => {
+    const ed = editorRef.current
+    if (!ed) return
+    const insert = (content: PMNode[]) => {
+      const chain = ed.chain().focus()
+      const pos = at === undefined ? undefined : Math.min(at, ed.state.doc.content.size)
+      ;(pos === undefined ? chain.insertContent(content) : chain.insertContentAt(pos, content)).run()
+    }
+    if (latest.current.imagePaste === "chip") {
+      const items = files.map((file) => ({ file, id: newAttachmentId(), name: attachmentName(file) }))
+      // Keep chips off the preceding word: "done.[chip]" → "done. [chip]".
+      const $at = at === undefined ? ed.state.selection.$from : ed.state.doc.resolve(Math.min(at, ed.state.doc.content.size))
+      const before = $at.parent.isTextblock ? $at.parent.textBetween(Math.max(0, $at.parentOffset - 1), $at.parentOffset, "", "\uFFFC") : ""
+      const lead: PMNode[] = before && !/\s/.test(before) ? [{ type: "text", text: " " }] : []
+      insert([
+        ...lead,
+        ...items.flatMap(({ id, name }): PMNode[] => [
+          { type: "gbAttachment", attrs: { id, name } },
+          { type: "text", text: " " },
+        ]),
+      ])
+      for (const { file, id, name } of items) {
+        const base = { id, name, size: file.size, type: file.type, file }
+        readFileAsDataURL(file).then(
+          (src) => latest.current.onAttachmentAdd?.({ ...base, src }),
+          () => latest.current.onAttachmentAdd?.(base)
+        )
+      }
+      return
+    }
+    void Promise.all(
+      files.map((file) =>
+        readFileAsDataURL(file).then(
+          (src): PMNode => ({ type: "gbFigure", attrs: { src, alt: attachmentName(file), caption: "" } }),
+          () => null
+        )
+      )
+    ).then((figures) => {
+      const content = figures.filter((f): f is PMNode => f !== null)
+      if (content.length && !ed.isDestroyed) insert(content)
+    })
+  }
 
   const parseAndTrack = (md: string) => {
     const doc = parseMarkdown(md)
@@ -168,19 +250,44 @@ export function GitbookEditor({
     }),
     editorProps: {
       handleKeyDown: (_view, event) => onKeyDown?.(event) ?? false,
-      handlePaste: (_view, event) => onPaste?.(event) ?? false,
+      handlePaste: (view, event) => {
+        if (latest.current.onPaste?.(event)) return true
+        if (!view.editable || view.state.selection.$from.parent.type.spec.code) return false
+        const files = imageFilesFrom(event.clipboardData, { ignoreWithText: true })
+        if (!files.length) return false
+        event.preventDefault()
+        insertImageFiles(files)
+        return true
+      },
+      handleDrop: (view, event, _slice, moved) => {
+        if (moved || !view.editable) return false
+        const files = imageFilesFrom(event.dataTransfer)
+        if (!files.length) return false
+        event.preventDefault()
+        insertImageFiles(files, view.posAtCoords({ left: event.clientX, top: event.clientY })?.pos)
+        return true
+      },
     },
     ...(controlled ? { content: astToTiptap(parseAndTrack(markdown as string)) } : {}),
+    onCreate({ editor }) {
+      attachmentIds.current = collectAttachmentIds(editor.state.doc)
+    },
     onUpdate({ editor }) {
+      const ids = collectAttachmentIds(editor.state.doc)
+      const removed = [...attachmentIds.current].filter((id) => !ids.has(id))
+      attachmentIds.current = ids
+      if (removed.length) latest.current.onAttachmentRemove?.(removed)
       if (!onChange) return
       const ast = tiptapToAst(editor.getJSON() as PMNode)
       if (citationsRef.current?.length) ast.citations = citationsRef.current
-      const md = serializeMarkdown(ast)
+      const md = serializeEditorMarkdown(ast)
       lastEmitted.current = md
       onChange(md)
     },
   })
 
+  editorRef.current = editor ?? null
+
   // Surface the editor instance to the host (for awareness, commands, etc.).
   useEffect(() => {
     onEditorReady?.(editor ?? null)
@@ -194,6 +301,8 @@ export function GitbookEditor({
     const doc = parseMarkdown(markdown as string)
     citationsRef.current = doc.citations
     editor.commands.setContent(astToTiptap(doc), { emitUpdate: false })
+    // Chips replaced by the host's own markdown aren't "removed" by the user.
+    attachmentIds.current = collectAttachmentIds(editor.state.doc)
   }, [editor, controlled, markdown])
 
   const runtime = useMemo(() => ({
@@ -202,7 +311,9 @@ export function GitbookEditor({
     sourceAutoSave,
     ...(onSourceSaved ? { onSourceSaved } : {}),
     ...(onSourceError ? { onSourceError } : {}),
-  }), [onSourceError, onSourceSaved, sourceAutoSave, sourceClient, sourcePreview])
+    ...(attachments ? { attachments } : {}),
+    ...(onAttachmentOpen ? { onAttachmentOpen } : {}),
+  }), [attachments, onAttachmentOpen, onSourceError, onSourceSaved, sourceAutoSave, sourceClient, sourcePreview])
 
   if (!editor) return null
 

package/src/editor/attachments.tsx

@@ -0,0 +1,354 @@
+import { Node, mergeAttributes } from "@tiptap/core"
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model"
+import { NodeViewWrapper, ReactNodeViewRenderer, type NodeViewProps } from "@tiptap/react"
+import { ImageIcon } from "lucide-react"
+import { useCallback, useEffect, useLayoutEffect, useRef, useState, type CSSProperties } from "react"
+import { createPortal } from "react-dom"
+
+import { useEditorRuntime } from "./runtime"
+
+/** A file the host owns, referenced from the document by an attachment chip. */
+export interface EditorAttachment {
+  id: string
+  name: string
+  /** Full image URL (typically a data URL). Also used for the chip thumbnail. */
+  src?: string
+  /** Size in bytes. */
+  size?: number
+  /** MIME type. */
+  type?: string
+}
+
+/** The URL scheme attachment chips serialize to: `![name](attachment:<id>)`. */
+export const ATTACHMENT_SCHEME = "attachment:"
+
+export function newAttachmentId(): string {
+  const rand =
+    typeof crypto !== "undefined" && "randomUUID" in crypto
+      ? crypto.randomUUID().replace(/-/g, "").slice(0, 12)
+      : Math.random().toString(36).slice(2, 14)
+  return `att-${rand}`
+}
+
+/**
+ * The name a pasted/dropped file gets in the document. Clipboard screenshots
+ * usually arrive as "image.png"; unnamed ones get that too. Characters that
+ * would break `![alt](src)` / `alt="…"` are replaced.
+ */
+export function attachmentName(file: File): string {
+  const name = (file.name || "image.png").replace(/[[\]"<>\r\n]/g, "_").trim()
+  return name || "image.png"
+}
+
+/** "84 KB", "1.3 MB". */
+export function formatBytes(bytes: number | undefined): string {
+  if (bytes === undefined || !Number.isFinite(bytes) || bytes < 0) return ""
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`
+}
+
+export function readFileAsDataURL(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader()
+    reader.onload = () => resolve(String(reader.result ?? ""))
+    reader.onerror = () => reject(reader.error ?? new Error(`Could not read ${file.name}`))
+    reader.readAsDataURL(file)
+  })
+}
+
+/**
+ * Image files carried by a paste or drop. Clipboard data that also has plain
+ * text (e.g. a Word/Excel selection, which ships a rendered PNG alongside the
+ * text) is left to the normal text paste.
+ */
+export function imageFilesFrom(data: DataTransfer | null, { ignoreWithText = false } = {}): File[] {
+  if (!data) return []
+  const files = Array.from(data.files ?? []).filter((f) => f.type.startsWith("image/"))
+  if (!files.length) return []
+  if (ignoreWithText && data.getData("text/plain").trim()) return []
+  return files
+}
+
+/** Ids of every attachment chip in a document. */
+export function collectAttachmentIds(doc: ProseMirrorNode): Set<string> {
+  const ids = new Set<string>()
+  doc.descendants((node) => {
+    if (node.type.name === "gbAttachment" && node.attrs.id) ids.add(String(node.attrs.id))
+    return node.isBlock || node.type.name === "doc"
+  })
+  return ids
+}
+
+// ---------- Hover card ----------
+
+const HOVER_DELAY = 150
+const HIDE_GRACE = 120
+const GAP = 8
+const MARGIN = 8
+
+function AttachmentHoverCard({
+  anchor,
+  attachment,
+}: {
+  anchor: HTMLElement
+  attachment: EditorAttachment
+}) {
+  const cardRef = useRef<HTMLDivElement>(null)
+  const [pos, setPos] = useState<{ top: number; left: number } | null>(null)
+
+  const place = useCallback(() => {
+    const card = cardRef.current
+    if (!card) return
+    const a = anchor.getBoundingClientRect()
+    const { width, height } = card.getBoundingClientRect()
+    const vw = window.innerWidth
+    const vh = window.innerHeight
+    let top = a.top - GAP - height
+    if (top < MARGIN && a.bottom + GAP + height <= vh - MARGIN) top = a.bottom + GAP
+    top = Math.max(MARGIN, top)
+    const left = Math.min(Math.max(MARGIN, a.left + a.width / 2 - width / 2), Math.max(MARGIN, vw - MARGIN - width))
+    setPos({ top, left })
+  }, [anchor])
+
+  useLayoutEffect(place, [place, attachment.src])
+
+  const size = formatBytes(attachment.size)
+  const style: CSSProperties = pos
+    ? { top: pos.top, left: pos.left }
+    : { top: 0, left: 0, visibility: "hidden" }
+  return createPortal(
+    <div ref={cardRef} className="gb-attachment-card" style={style} role="tooltip">
+      {attachment.src ? (
+        <img className="gb-attachment-card-img" src={attachment.src} alt={attachment.name} onLoad={place} />
+      ) : (
+        <div className="gb-attachment-card-empty">
+          <ImageIcon className="size-5" />
+        </div>
+      )}
+      <div className="gb-attachment-card-meta">
+        <span className="gb-attachment-card-name">{attachment.name}</span>
+        {size && <span className="gb-attachment-card-size"> · {size}</span>}
+      </div>
+    </div>,
+    document.body
+  )
+}
+
+// ---------- Built-in viewer ----------
+
+function AttachmentViewer({ attachment, onClose }: { attachment: EditorAttachment; onClose: () => void }) {
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        e.preventDefault()
+        e.stopPropagation()
+        onClose()
+      }
+    }
+    document.addEventListener("keydown", onKey, true)
+    return () => document.removeEventListener("keydown", onKey, true)
+  }, [onClose])
+
+  return createPortal(
+    <div
+      className="gb-attachment-viewer"
+      role="dialog"
+      aria-modal="true"
+      aria-label={attachment.name}
+      onMouseDown={(e) => e.preventDefault()}
+      onClick={onClose}
+    >
+      {attachment.src ? (
+        <img className="gb-attachment-viewer-img" src={attachment.src} alt={attachment.name} />
+      ) : (
+        <div className="gb-attachment-viewer-empty">
+          <ImageIcon className="size-6" />
+          {attachment.name}
+        </div>
+      )}
+    </div>,
+    document.body
+  )
+}
+
+// ---------- Chip ----------
+
+function AttachmentView({ node, selected, editor }: NodeViewProps) {
+  const { attachments, onAttachmentOpen } = useEditorRuntime()
+  const id = String(node.attrs.id ?? "")
+  const stored = attachments?.find((a) => a.id === id)
+  const attachment: EditorAttachment = { ...stored, id, name: stored?.name || String(node.attrs.name || "image") }
+  const size = formatBytes(attachment.size)
+
+  const chipRef = useRef<HTMLSpanElement>(null)
+  const [hovered, setHovered] = useState(false)
+  const [focused, setFocused] = useState(false)
+  const [dismissed, setDismissed] = useState(false)
+  const [viewing, setViewing] = useState(false)
+  const showTimer = useRef<number | undefined>(undefined)
+  const hideTimer = useRef<number | undefined>(undefined)
+
+  const clearTimers = () => {
+    window.clearTimeout(showTimer.current)
+    window.clearTimeout(hideTimer.current)
+  }
+  useEffect(() => clearTimers, [])
+
+  // A fresh selection of the chip re-arms a card dismissed with Escape.
+  useEffect(() => {
+    if (selected) setDismissed(false)
+  }, [selected])
+
+  const cardOpen =
+    !viewing && !dismissed && (hovered || focused || (selected && editor.isFocused))
+
+  useEffect(() => {
+    if (!cardOpen) return
+    const hide = () => {
+      clearTimers()
+      setHovered(false)
+      setDismissed(true)
+    }
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") hide()
+    }
+    window.addEventListener("scroll", hide, true)
+    document.addEventListener("keydown", onKey, true)
+    return () => {
+      window.removeEventListener("scroll", hide, true)
+      document.removeEventListener("keydown", onKey, true)
+    }
+  }, [cardOpen])
+
+  const open = () => {
+    clearTimers()
+    setHovered(false)
+    if (onAttachmentOpen) onAttachmentOpen(attachment)
+    else setViewing(true)
+  }
+
+  const closeViewer = useCallback(() => setViewing(false), [])
+
+  return (
+    <NodeViewWrapper as="span" className="gb-attachment-wrap" contentEditable={false}>
+      <span
+        ref={chipRef}
+        className="gb-attachment"
+        role="button"
+        tabIndex={0}
+        aria-label={size ? `${attachment.name}, ${size}` : attachment.name}
+        data-attachment-id={id}
+        onMouseEnter={() => {
+          window.clearTimeout(hideTimer.current)
+          setDismissed(false)
+          showTimer.current = window.setTimeout(() => setHovered(true), HOVER_DELAY)
+        }}
+        onMouseLeave={() => {
+          window.clearTimeout(showTimer.current)
+          hideTimer.current = window.setTimeout(() => setHovered(false), HIDE_GRACE)
+        }}
+        onFocus={() => {
+          setDismissed(false)
+          setFocused(true)
+        }}
+        onBlur={() => setFocused(false)}
+        // Keep the caret where it is — the chip is a button, not a text target.
+        onMouseDown={(e) => e.preventDefault()}
+        onClick={(e) => {
+          e.preventDefault()
+          open()
+        }}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault()
+            e.stopPropagation()
+            open()
+          }
+        }}
+      >
+        <span className="gb-attachment-thumb">
+          {attachment.src ? (
+            <img src={attachment.src} alt="" draggable={false} />
+          ) : (
+            <ImageIcon className="gb-attachment-thumb-icon" />
+          )}
+        </span>
+        <span className="gb-attachment-name">{attachment.name}</span>
+        {size && <span className="gb-attachment-size">{size}</span>}
+      </span>
+      {cardOpen && chipRef.current && <AttachmentHoverCard anchor={chipRef.current} attachment={attachment} />}
+      {viewing && <AttachmentViewer attachment={attachment} onClose={closeViewer} />}
+    </NodeViewWrapper>
+  )
+}
+
+declare module "@tiptap/core" {
+  interface Commands<ReturnType> {
+    gbAttachment: {
+      /** Delete every attachment chip with this id. */
+      removeAttachment: (id: string) => ReturnType
+    }
+  }
+}
+
+/**
+ * Inline attachment chip (`![name](attachment:<id>)`). The file itself lives in
+ * the host's attachment store; the node only carries the id and display name.
+ */
+export const GbAttachment = Node.create({
+  name: "gbAttachment",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  draggable: false,
+  addAttributes() {
+    return {
+      id: { default: "" },
+      name: { default: "" },
+    }
+  },
+  parseHTML() {
+    return [
+      {
+        tag: "span[data-gb-attachment]",
+        getAttrs: (el) => ({
+          id: (el as HTMLElement).getAttribute("data-gb-attachment") ?? "",
+          name: (el as HTMLElement).getAttribute("data-name") ?? "",
+        }),
+      },
+    ]
+  },
+  renderHTML({ HTMLAttributes, node }) {
+    return [
+      "span",
+      mergeAttributes(HTMLAttributes, { "data-gb-attachment": node.attrs.id, "data-name": node.attrs.name }),
+      String(node.attrs.name),
+    ]
+  },
+  renderText({ node }) {
+    return String(node.attrs.name)
+  },
+  addCommands() {
+    return {
+      removeAttachment:
+        (id) =>
+        ({ tr, state, dispatch }) => {
+          const ranges: Array<[number, number]> = []
+          state.doc.descendants((node, pos) => {
+            if (node.type.name === this.name && node.attrs.id === id) ranges.push([pos, pos + node.nodeSize])
+          })
+          if (!ranges.length) return false
+          if (dispatch) {
+            for (const [from, to] of ranges.reverse()) tr.delete(from, to)
+          }
+          return true
+        },
+    }
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(AttachmentView)
+  },
+})

package/src/editor/convert.ts

@@ -1,4 +1,19 @@
-import { plainText, type Block, type DocumentNode, type Inline, type ListItemNode } from "@brett_lamy/docstream/gitbook"
+import {
+  plainText,
+  serializeMarkdown,
+  type Block,
+  type DocumentNode,
+  type Inline,
+  type ListItemNode,
+} from "@brett_lamy/docstream/gitbook"
+
+// Attachment chips live in markdown as images with an `attachment:<id>` URL.
+const ATTACHMENT_SCHEME = "attachment:"
+const isAttachmentSrc = (src: string | undefined) => !!src && src.startsWith(ATTACHMENT_SCHEME)
+const attachmentPM = (src: string, alt: string | undefined): PMNode => ({
+  type: "gbAttachment",
+  attrs: { id: src.slice(ATTACHMENT_SCHEME.length), name: alt ?? "" },
+})
 
 // TipTap/ProseMirror JSON shape (loosely typed on purpose)
 export interface PMNode {
@@ -23,6 +38,7 @@ function inlineToPM(nodes: Inline[]): PMNode[] {
           attrs: { kind: n.kind, id: n.id, url: n.url ?? "", label: n.label ?? "" },
         }
       }
+      if (n.type === "image" && isAttachmentSrc(n.src)) return attachmentPM(n.src, n.alt)
       if (n.type === "image") {
         return {
           type: "gbInlineImage",
@@ -135,6 +151,8 @@ function blockToPM(b: Block): PMNode {
         content: b.columns.map((c) => ({ type: "gbColumn", content: blocksPM(c.children) })),
       }
     case "figure":
+      // A chip alone on its line parses as a figure; it is still a chip.
+      if (isAttachmentSrc(b.src)) return { type: "paragraph", content: [attachmentPM(b.src, b.alt)] }
       return { type: "gbFigure", attrs: { src: b.src, alt: b.alt, caption: b.caption } }
     case "list":
       return {
@@ -199,11 +217,26 @@ export function astToTiptap(doc: DocumentNode): PMNode {
 function pmTextToInline(nodes: PMNode[] | undefined): Inline[] {
   if (!nodes) return []
   return nodes
-    .filter((n) => (n.type === "text" && n.text) || n.type === "gbInlineImage" || n.type === "gbReference")
+    .filter(
+      (n) =>
+        (n.type === "text" && n.text) ||
+        n.type === "gbInlineImage" ||
+        n.type === "gbReference" ||
+        n.type === "gbAttachment"
+    )
     .map((n): Inline => {
+      if (n.type === "gbAttachment") {
+        const a = n.attrs ?? {}
+        return {
+          type: "image",
+          src: `${ATTACHMENT_SCHEME}${String(a.id ?? "")}`,
+          ...(a.name ? { alt: String(a.name) } : {}),
+        }
+      }
       if (n.type === "gbReference") {
         const a = n.attrs ?? {}
-        const kind = a.kind === "tag" ? "tag" : a.kind === "citation" ? "citation" : "mention"
+        const kind =
+          a.kind === "tag" || a.kind === "codebase" || a.kind === "citation" ? a.kind : "mention"
         return {
           type: "reference",
           kind,
@@ -397,3 +430,19 @@ function pmToBlocks(nodes: PMNode[] | undefined): Block[] {
 export function tiptapToAst(doc: PMNode): DocumentNode {
   return { type: "doc", children: pmToBlocks(doc.content) }
 }
+
+// docstream writes inline images as `<img src alt />`; attachment chips read
+// better (and diff better) as plain markdown images.
+const ATTACHMENT_IMG = /<img src="(attachment:[^"\s]+)"(?: alt="([^"]*)")? \/>/g
+
+/**
+ * Serialize an editor AST to GitBook markdown, writing attachment chips as
+ * `![name](attachment:<id>)`. Use this instead of `serializeMarkdown` for
+ * editor output.
+ */
+export function serializeEditorMarkdown(doc: DocumentNode): string {
+  return serializeMarkdown(doc).replace(ATTACHMENT_IMG, (img: string, src: string, alt = "") =>
+    // `]` can't be escaped in `![alt]`; such names keep the <img> form.
+    alt.includes("]") ? img : `![${alt}](${src})`
+  )
+}

package/src/editor/extensions.ts

@@ -6,7 +6,7 @@ import { getSchema, type AnyExtension } from "@tiptap/core"
 import type { Schema } from "@tiptap/pm/model"
 import { GbCodeBlock, gitbookNodes } from "./nodes"
 import { SlashMenu, createSlashMenu, type SlashItem } from "./slash-menu"
-import { createReferenceSuggestion } from "./reference-menu"
+import { createReferenceSuggestion, type ReferenceSource } from "./reference-menu"
 
 // Carries GitBook's data-view (e.g. "cards") through the editor untouched.
 export const GbTable = Table.extend({
@@ -15,15 +15,26 @@ export const GbTable = Table.extend({
   },
 })
 
+export interface ReferenceSources {
+  /** "@" — people, agents, … */
+  mentions?: ReferenceSource
+  /** "#" — channels, tags, … */
+  tags?: ReferenceSource
+  /** "$" — codebases (`$repo` / `$org/repo`). Enables the "$" trigger. */
+  codebases?: ReferenceSource
+}
+
 export interface GitbookExtensionOptions {
   placeholder?: string
   /** Built-in "/" slash menu: true (default), false, or a custom item list. */
   slashMenu?: boolean | { items?: SlashItem[] }
   /**
-   * The "@" / "#" reference chip pickers: true (default), false, or lists of
-   * known ids to offer. Free-form entry always works.
+   * The reference chip pickers: true (default: "@" and "#" with free-form entry),
+   * false, or per-trigger sources — static lists or async `(query) => options`.
+   * "$" (codebases) is only enabled when a `codebases` source is given, so a
+   * dollar sign in ordinary prose never opens a menu.
    */
-  references?: boolean | { mentions?: string[]; tags?: string[] }
+  references?: boolean | ReferenceSources
   /**
    * Disable StarterKit's built-in undo/redo. Required when wiring Yjs
    * Collaboration, which provides its own shared history.
@@ -73,6 +84,7 @@ export function createGitbookExtensions(options: GitbookExtensionOptions = {}):
       createReferenceSuggestion({ char: "@", ...(opts.mentions ? { items: opts.mentions } : {}) }),
       createReferenceSuggestion({ char: "#", ...(opts.tags ? { items: opts.tags } : {}) })
     )
+    if (opts.codebases) list.push(createReferenceSuggestion({ char: "$", items: opts.codebases }))
   }
 
   list.push(...extensions)

package/src/editor/nodes.tsx

@@ -13,6 +13,7 @@ import {
   AtSign,
   CheckCircle2,
   ChevronDown,
+  FolderGit2,
   Hash,
   Info,
   Link2,
@@ -31,6 +32,7 @@ import { ReplayPreview, isReplayQaUrl } from "@brett_lamy/docstream/replay"
 import { VideoEmbed } from "@brett_lamy/docstream/video"
 import { SourceFileEditor } from "./SourceFileEditor"
 import { useEditorRuntime } from "./runtime"
+import { GbAttachment } from "./attachments"
 
 function useDebouncedValue<T>(value: T, delay = 350): T {
   const [debounced, setDebounced] = useState(value)
@@ -792,7 +794,13 @@ function ReferenceView({ node }: NodeViewProps) {
         </span>
       ) : (
         <span className={`gb-ref gb-ref-${kind}`}>
-          {kind === "mention" ? <AtSign className="gb-ref-icon" /> : <Hash className="gb-ref-icon" />}
+          {kind === "mention" ? (
+            <AtSign className="gb-ref-icon" />
+          ) : kind === "codebase" ? (
+            <FolderGit2 className="gb-ref-icon" />
+          ) : (
+            <Hash className="gb-ref-icon" />
+          )}
           {id}
         </span>
       )}
@@ -818,7 +826,14 @@ export const GbReference = Node.create({
     return [{ tag: "span[data-gb-ref]" }]
   },
   renderHTML({ HTMLAttributes, node }) {
-    const sigil = node.attrs.kind === "mention" ? "@" : node.attrs.kind === "tag" ? "#" : "^"
+    const sigil =
+      node.attrs.kind === "mention"
+        ? "@"
+        : node.attrs.kind === "tag"
+          ? "#"
+          : node.attrs.kind === "codebase"
+            ? "$"
+            : "^"
     return [
       "span",
       mergeAttributes(HTMLAttributes, { "data-gb-ref": node.attrs.kind, "data-gb-ref-id": node.attrs.id }),
@@ -969,4 +984,5 @@ export const gitbookNodes = [
   GbOpenapi,
   GbInlineImage,
   GbReference,
+  GbAttachment,
 ]

package/src/editor/reference-menu.tsx

@@ -1,32 +1,88 @@
 import { Extension, type Editor, type Range } from "@tiptap/core"
 import Suggestion from "@tiptap/suggestion"
 import { PluginKey } from "@tiptap/pm/state"
-import { AtSign, Hash } from "lucide-react"
+import { AtSign, FolderGit2, Hash, type LucideIcon } from "lucide-react"
 
 import { createSuggestionRender, type SuggestionMenuItem } from "./suggestion-menu"
 
-export type ReferenceTrigger = "@" | "#"
+export type ReferenceTrigger = "@" | "#" | "$"
 
-interface ReferenceItem extends SuggestionMenuItem {
+/** One pickable reference: the chip stores `id`; the rest only decorates the menu. */
+export interface ReferenceOption {
   id: string
+  /** Display name shown next to the id (e.g. "Luna" for `@luna`). */
+  label?: string
+  /** Secondary line (e.g. an email, "agent · claude-code", a topic). */
+  description?: string
+  /** Section header; consecutive options with the same group are listed together. */
+  group?: string
 }
 
+/**
+ * Where a trigger's options come from: a static list (filtered by the editor), or a
+ * function the host answers per query — sync or async, already filtered.
+ */
+export type ReferenceSource =
+  | readonly (string | ReferenceOption)[]
+  | ((query: string) => readonly ReferenceOption[] | Promise<readonly ReferenceOption[]>)
+
 export interface ReferenceSuggestionOptions {
   char: ReferenceTrigger
-  /** Known ids offered in the picker; free-form entry always works. */
-  items?: string[]
+  /** Options offered in the picker; free-form entry works unless disabled. */
+  items?: ReferenceSource
+  /** Offer inserting the raw query when nothing matches exactly (default true). */
+  allowFreeForm?: boolean
+}
+
+interface ReferenceItem extends SuggestionMenuItem {
+  id: string
 }
 
-const KIND: Record<ReferenceTrigger, "mention" | "tag"> = { "@": "mention", "#": "tag" }
+const KIND: Record<ReferenceTrigger, "mention" | "tag" | "codebase"> = {
+  "@": "mention",
+  "#": "tag",
+  $: "codebase",
+}
+const ICON: Record<ReferenceTrigger, LucideIcon> = { "@": AtSign, "#": Hash, $: FolderGit2 }
+const EMPTY: Record<ReferenceTrigger, string> = {
+  "@": "Type a name to mention",
+  "#": "Type a channel or tag",
+  $: "Type a codebase",
+}
+const MAX_OPTIONS = 50
+
+function normalize(option: string | ReferenceOption): ReferenceOption {
+  return typeof option === "string" ? { id: option } : option
+}
+
+function matches(option: ReferenceOption, query: string): boolean {
+  if (!query) return true
+  return [option.id, option.label ?? ""].some((value) => value.toLowerCase().includes(query))
+}
+
+/** Resolve a source for a query into options (exported for hosts' tests). */
+export async function resolveReferenceOptions(
+  source: ReferenceSource | undefined,
+  query: string,
+): Promise<ReferenceOption[]> {
+  if (source === undefined) return []
+  if (typeof source === "function") return [...(await source(query))].slice(0, MAX_OPTIONS)
+  const q = query.toLowerCase()
+  return source.map(normalize).filter((option) => matches(option, q)).slice(0, MAX_OPTIONS)
+}
 
 /**
- * An `@mention` / `#tag` picker built on @tiptap/suggestion. Filters the host's
- * known ids and always offers inserting the raw query, so typing `@anything⏎`
- * works with no list configured.
+ * An `@mention` / `#tag` / `$codebase` picker built on @tiptap/suggestion. Options come
+ * from the host (static or async) and the raw query is offered as a free-form entry,
+ * so `@anything⏎` works with no source configured.
  */
-export function createReferenceSuggestion({ char, items = [] }: ReferenceSuggestionOptions) {
+export function createReferenceSuggestion({
+  char,
+  items,
+  allowFreeForm = true,
+}: ReferenceSuggestionOptions) {
   const kind = KIND[char]
-  const icon = char === "@" ? AtSign : Hash
+  const icon = ICON[char]
   return Extension.create({
     name: `${kind}Suggestion`,
     addProseMirrorPlugins() {
@@ -39,13 +95,26 @@ export function createReferenceSuggestion({ char, items = [] }: ReferenceSuggest
           // Each Suggestion plugin needs its own key — the default is shared
           // with the slash menu and would collide.
           pluginKey: new PluginKey(`${kind}Suggestion`),
-          items: ({ query }) => {
-            const q = query.toLowerCase()
-            const matches = items
-              .filter((id) => id.toLowerCase().includes(q))
-              .map((id) => ({ id, title: `${char}${id}`, icon }))
-            const freeForm = query && !items.some((id) => id.toLowerCase() === q)
-            return freeForm ? [...matches, { id: query, title: `${char}${query}`, icon }] : matches
+          items: async ({ query }) => {
+            let options: ReferenceOption[]
+            try {
+              options = await resolveReferenceOptions(items, query)
+            } catch {
+              options = []
+            }
+            const menu: ReferenceItem[] = options.map((option) => ({
+              id: option.id,
+              title: `${char}${option.id}`,
+              icon,
+              ...(option.label || option.description
+                ? { description: [option.label, option.description].filter(Boolean).join(" · ") }
+                : {}),
+              ...(option.group ? { group: option.group } : {}),
+            }))
+            const exact = options.some((option) => option.id.toLowerCase() === query.toLowerCase())
+            return allowFreeForm && query && !exact
+              ? [...menu, { id: query, title: `${char}${query}`, icon }]
+              : menu
           },
           command: ({ editor, range, props }) => {
             ;(editor as Editor)
@@ -58,9 +127,7 @@ export function createReferenceSuggestion({ char, items = [] }: ReferenceSuggest
               ])
               .run()
           },
-          render: createSuggestionRender<ReferenceItem>(
-            char === "@" ? "Type a name to mention" : "Type a tag"
-          ),
+          render: createSuggestionRender<ReferenceItem>(EMPTY[char]),
         }),
       ]
     },

package/src/editor/runtime.tsx

@@ -1,6 +1,7 @@
 import { createContext, useContext, type ReactNode } from "react"
 
 import type { SourceFileSnapshot, SourceReferenceClient } from "@brett_lamy/docstream/source"
+import type { EditorAttachment } from "./attachments"
 
 export interface EditorRuntimeOptions {
   sourceClient?: SourceReferenceClient
@@ -8,6 +9,8 @@ export interface EditorRuntimeOptions {
   sourceAutoSave?: boolean | number
   onSourceSaved?: (snapshot: SourceFileSnapshot) => void
   onSourceError?: (error: Error) => void
+  attachments?: EditorAttachment[]
+  onAttachmentOpen?: (attachment: EditorAttachment) => void
 }
 
 const EditorRuntimeContext = createContext<EditorRuntimeOptions>({})

package/src/editor/suggestion-menu.tsx

@@ -12,11 +12,15 @@ import type { SuggestionProps } from "@tiptap/suggestion"
 import { ReactRenderer } from "@tiptap/react"
 import type { LucideIcon } from "lucide-react"
 
-// Shared popup used by the "/" slash menu and the "@"/"#" reference menus.
+// Shared popup used by the "/" slash menu and the "@"/"#"/"$" reference menus.
 
 export interface SuggestionMenuItem {
   title: string
   icon: LucideIcon
+  /** Secondary text shown after the title (e.g. a display name or email). */
+  description?: string
+  /** Section header; shown when it differs from the previous item's group. */
+  group?: string
 }
 
 export interface MenuProps<Item extends SuggestionMenuItem> {
@@ -97,21 +101,26 @@ export const SuggestionMenuView = forwardRef<MenuHandle, MenuProps<SuggestionMen
       >
         {items.length === 0 && <div className="slash-empty">{emptyLabel}</div>}
         {items.map((item, i) => (
-          <button
-            key={item.title}
-            ref={(el) => {
-              itemRefs.current[i] = el
-            }}
-            className={`slash-item ${i === index ? "slash-item-active" : ""}`}
-            onMouseEnter={() => setIndex(i)}
-            onMouseDown={(e) => {
-              e.preventDefault()
-              command(item)
-            }}
-          >
-            <item.icon className="size-4" />
-            <span>{item.title}</span>
-          </button>
+          <div key={`${item.group ?? ""}:${item.title}:${i}`} className="slash-row">
+            {item.group && item.group !== items[i - 1]?.group && (
+              <div className="slash-group">{item.group}</div>
+            )}
+            <button
+              ref={(el) => {
+                itemRefs.current[i] = el
+              }}
+              className={`slash-item ${i === index ? "slash-item-active" : ""}`}
+              onMouseEnter={() => setIndex(i)}
+              onMouseDown={(e) => {
+                e.preventDefault()
+                command(item)
+              }}
+            >
+              <item.icon className="size-4" />
+              <span>{item.title}</span>
+              {item.description && <span className="slash-item-description">{item.description}</span>}
+            </button>
+          </div>
         ))}
       </div>
     )

package/src/index.ts

@@ -1,17 +1,23 @@
 export { GitbookEditor } from "./editor/Editor"
-export type { GitbookEditorProps } from "./editor/Editor"
-export { astToTiptap, tiptapToAst } from "./editor/convert"
+export type { GitbookEditorProps, EditorAttachment } from "./editor/Editor"
+export { astToTiptap, tiptapToAst, serializeEditorMarkdown } from "./editor/convert"
 export type { PMNode } from "./editor/convert"
 
 // Building blocks for composing a custom editor (e.g. with Yjs collaboration
 // or a bespoke slash menu) instead of the batteries-included GitbookEditor.
 export { createGitbookExtensions, getGitbookSchema, GbTable } from "./editor/extensions"
-export type { GitbookExtensionOptions } from "./editor/extensions"
+export type { GitbookExtensionOptions, ReferenceSources } from "./editor/extensions"
 export { gitbookNodes, GbCodeBlock, GbReference } from "./editor/nodes"
+export { GbAttachment, formatBytes } from "./editor/attachments"
 export { SlashMenu, createSlashMenu, SLASH_ITEMS } from "./editor/slash-menu"
 export type { SlashItem } from "./editor/slash-menu"
-export { createReferenceSuggestion } from "./editor/reference-menu"
-export type { ReferenceSuggestionOptions, ReferenceTrigger } from "./editor/reference-menu"
+export { createReferenceSuggestion, resolveReferenceOptions } from "./editor/reference-menu"
+export type {
+  ReferenceOption,
+  ReferenceSource,
+  ReferenceSuggestionOptions,
+  ReferenceTrigger,
+} from "./editor/reference-menu"
 export { SuggestionMenuView, createSuggestionRender } from "./editor/suggestion-menu"
 export type { SuggestionMenuItem } from "./editor/suggestion-menu"
 export { ReactDemoEditor } from "./editor/ReactDemoEditor"

package/src/styles.css

@@ -583,14 +583,15 @@
 }
 .gb-code > pre code { background: none; padding: 0; font-size: inherit; color: inherit; }
 /* gpu-lexer span classes (palette shared with docstream's HighlightedCode). */
-.gb-code .gb-syntax-comment { color: #6b6b78; font-style: italic; }
-.gb-code .gb-syntax-string { color: #a5d6a7; }
-.gb-code .gb-syntax-number { color: #f78c6c; }
-.gb-code .gb-syntax-keyword { color: #c792ea; }
-.gb-code .gb-syntax-type { color: #ffcb6b; }
-.gb-code .gb-syntax-function { color: #82aaff; }
-.gb-code .gb-syntax-constant { color: #f07178; }
-.gb-code .gb-syntax-operator { color: #89ddff; }
+/* Same palette and custom properties as Docstream's .docs-tok-*: follows the host color-scheme. */
+.gb-code .gb-syntax-comment { color: var(--docs-tok-comment, light-dark(#6E6E7A, #8A8A98)); font-style: italic; }
+.gb-code .gb-syntax-string { color: var(--docs-tok-string, light-dark(#23803A, #A5D6A7)); }
+.gb-code .gb-syntax-number { color: var(--docs-tok-number, light-dark(#C2410C, #F78C6C)); }
+.gb-code .gb-syntax-keyword { color: var(--docs-tok-keyword, light-dark(#8839C4, #C792EA)); }
+.gb-code .gb-syntax-type { color: var(--docs-tok-type, light-dark(#A15C00, #FFCB6B)); }
+.gb-code .gb-syntax-function { color: var(--docs-tok-function, light-dark(#2F5BD3, #82AAFF)); }
+.gb-code .gb-syntax-constant { color: var(--docs-tok-constant, light-dark(#C8283F, #F07178)); }
+.gb-code .gb-syntax-operator { color: var(--docs-tok-operator, light-dark(#0B7285, #89DDFF)); }
 
 /* ── Updates / changelog (mirrors .docs-updates) ────────── */
 .gb-updates { margin: 0.85em 0; border-top: 1px solid var(--gb-border); }
@@ -650,6 +651,23 @@
 .slash-item-active { background: var(--accent, #f4f4f5); }
 .slash-item svg { color: var(--muted-foreground, #6b7280); }
 .slash-empty { padding: 8px 10px; font-size: 13px; color: var(--muted-foreground, #6b7280); }
+.slash-group {
+  padding: 8px 10px 3px;
+  font-size: 11px;
+  font-weight: 600;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--muted-foreground, #6b7280);
+}
+.slash-item-description {
+  margin-left: auto;
+  padding-left: 12px;
+  overflow: hidden;
+  font-size: 12px;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  color: var(--muted-foreground, #6b7280);
+}
 
 .gb-code-live {
   display: flex;
@@ -819,6 +837,12 @@
   color: var(--gb-muted-foreground);
 }
 
+.gb-ref-codebase {
+  border: 1px solid rgba(34, 197, 94, 0.45);
+  background: rgba(34, 197, 94, 0.1);
+  color: rgb(22, 163, 74);
+}
+
 .gb-cite {
   display: inline-block;
   padding: 1px 5px;
@@ -836,3 +860,163 @@
   outline: 2px solid var(--gb-primary);
   outline-offset: 1px;
 }
+
+/* ---- Attachment chips (pasted images in imagePaste="chip" mode) ---- */
+
+.gb-attachment-wrap {
+  display: inline;
+}
+
+.gb-attachment {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  max-width: 100%;
+  padding: 1px 7px 1px 3px;
+  border: 1px solid var(--gb-border);
+  border-radius: 7px;
+  background: var(--gb-muted);
+  color: var(--gb-text);
+  font-size: 0.85em;
+  line-height: 1.5;
+  vertical-align: middle;
+  cursor: pointer;
+  user-select: none;
+  transition: border-color 120ms ease, background-color 120ms ease;
+}
+.gb-attachment:hover {
+  border-color: var(--gb-muted-foreground);
+}
+.gb-attachment:focus {
+  outline: none;
+}
+.gb-attachment:focus-visible,
+.ProseMirror-selectednode .gb-attachment {
+  outline: 2px solid var(--gb-primary);
+  outline-offset: 1px;
+}
+
+.gb-attachment-thumb {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 16px;
+  overflow: hidden;
+  border-radius: 3px;
+  background: var(--gb-border);
+  color: var(--gb-muted-foreground);
+}
+.gb-attachment-thumb img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+.gb-attachment-thumb-icon {
+  width: 12px;
+  height: 12px;
+}
+
+.gb-attachment-name {
+  overflow: hidden;
+  font-weight: 500;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  max-width: 22ch;
+}
+.gb-attachment-size {
+  flex-shrink: 0;
+  color: var(--gb-muted-foreground);
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+
+/* Portaled to <body>, outside .gb — tokens resolve from the host directly. */
+.gb-attachment-card {
+  position: fixed;
+  z-index: 1000;
+  box-sizing: border-box;
+  max-width: calc(100vw - 16px);
+  padding: 6px;
+  border: 1px solid var(--border, #e5e7eb);
+  border-radius: 12px;
+  background: var(--card, #ffffff);
+  color: var(--card-foreground, var(--foreground, #111827));
+  font-family: var(--font-sans, ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif);
+  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.18), 0 2px 6px rgba(0, 0, 0, 0.08);
+  pointer-events: none;
+  animation: gb-attachment-in 120ms ease-out;
+}
+.gb-attachment-card-img {
+  display: block;
+  max-width: 360px;
+  max-height: 280px;
+  width: auto;
+  height: auto;
+  object-fit: contain;
+  border-radius: 7px;
+  background: var(--muted, #f4f4f5);
+}
+.gb-attachment-card-empty {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 160px;
+  height: 100px;
+  border-radius: 7px;
+  background: var(--muted, #f4f4f5);
+  color: var(--muted-foreground, #6b7280);
+}
+.gb-attachment-card-meta {
+  max-width: 360px;
+  padding: 6px 4px 1px;
+  overflow: hidden;
+  font-size: 12px;
+  line-height: 1.4;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+.gb-attachment-card-name { font-weight: 500; }
+.gb-attachment-card-size { color: var(--muted-foreground, #6b7280); }
+
+.gb-attachment-viewer {
+  position: fixed;
+  inset: 0;
+  z-index: 1001;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(0, 0, 0, 0.72);
+  cursor: zoom-out;
+  animation: gb-attachment-fade 140ms ease-out;
+}
+.gb-attachment-viewer-img {
+  max-width: 90vw;
+  max-height: 90vh;
+  object-fit: contain;
+  border-radius: 8px;
+  box-shadow: 0 24px 64px rgba(0, 0, 0, 0.45);
+}
+.gb-attachment-viewer-empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 10px;
+  color: #ffffff;
+  font-size: 14px;
+}
+
+@keyframes gb-attachment-in {
+  from { opacity: 0; transform: translateY(2px); }
+  to { opacity: 1; transform: none; }
+}
+@keyframes gb-attachment-fade {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .gb-attachment-card,
+  .gb-attachment-viewer { animation: none; }
+}